/******************************************************************************

 @file frame_control_queue.h

 @brief Frame Control Queue Module for Sensor Application
        基于POSIX消息队列实现，提供线程安全的frameControl队列，
        用于管理待发送的传感器数据

 *****************************************************************************/

#ifndef FRAME_CONTROL_QUEUE_H
#define FRAME_CONTROL_QUEUE_H

#ifdef __cplusplus
extern "C"
{
#endif

/******************************************************************************
 Includes
 *****************************************************************************/
#include <stdint.h>
#include <stdbool.h>

/******************************************************************************
 Constants and definitions
 *****************************************************************************/
/* 队列名称 */
#define FRAME_CONTROL_QUEUE_NAME    "/frame_ctrl_queue"

/* 队列最大容量 */
#define FRAME_CONTROL_QUEUE_SIZE    32

/******************************************************************************
 Typedefs
 *****************************************************************************/

/******************************************************************************
 Function Prototypes
 *****************************************************************************/

/*!
 * @brief       初始化frameControl队列
 *              必须在使用队列前调用此函数
 * 
 * @return      true - 成功
 *              false - 失败
 */
extern bool FrameControlQueue_init(void);

/*!
 * @brief       将frameControl添加到队列末尾
 * 
 * @param       frameControl - 要添加的frameControl值
 * 
 * @return      true - 成功入队
 *              false - 队列已满，入队失败
 */
extern bool FrameControlQueue_enqueue(uint16_t frameControl);

/*!
 * @brief       从队列头部取出frameControl
 * 
 * @param       pFrameControl - 用于存储取出的frameControl值的指针
 * 
 * @return      true - 成功出队
 *              false - 队列为空，出队失败
 */
extern bool FrameControlQueue_dequeue(uint16_t *pFrameControl);

/*!
 * @brief       查看队列头部的frameControl但不移除
 * 
 * @param       pFrameControl - 用于存储查看的frameControl值的指针
 * 
 * @return      true - 成功查看
 *              false - 队列为空
 */
extern bool FrameControlQueue_peek(uint16_t *pFrameControl);

/*!
 * @brief       检查队列是否为空
 * 
 * @return      true - 队列为空
 *              false - 队列不为空
 */
extern bool FrameControlQueue_isEmpty(void);

/*!
 * @brief       检查队列是否已满
 * 
 * @return      true - 队列已满
 *              false - 队列未满
 */
extern bool FrameControlQueue_isFull(void);

/*!
 * @brief       获取队列中当前的元素数量
 * 
 * @return      队列中的元素数量
 */
extern uint16_t FrameControlQueue_getCount(void);

/*!
 * @brief       清空队列
 */
extern void FrameControlQueue_clear(void);

/*!
 * @brief       批量入队多个frameControl
 * 
 * @param       pFrameControls - frameControl数组指针
 * @param       count - 数组元素数量
 * 
 * @return      实际成功入队的数量
 */
extern uint16_t FrameControlQueue_enqueueBatch(const uint16_t *pFrameControls, uint16_t count);

/*!
 * @brief       关闭并销毁队列（可选，用于清理资源）
 *              通常在程序退出时调用
 */
extern void FrameControlQueue_destroy(void);

#ifdef __cplusplus
}
#endif

#endif /* FRAME_CONTROL_QUEUE_H */

